Skip to content

Safety pass: crash and data-loss fixes, package traits, new README and CI - #8

Merged
drewmccormack merged 9 commits into
mainfrom
safety-pass
Sep 18, 2026
Merged

drewmccormack merged 9 commits into
mainfrom
safety-pass

Conversation

@drewmccormack

Copy link
Copy Markdown
Contributor

An audit of the whole package turned up a set of crash and data-loss bugs. This fixes the ones that could be fixed without a real cloud account, each with a test that failed first. The full list, with what is fixed and what is still open, is in AUDIT.md. User-visible changes are in CHANGELOG.md.

Source breaking

  • StoreCoordinator.merge() and Store.mergeHeads(...) now throw. In 0.9 a failed merge crashed the app through a try!.
  • LLVSBox and LLVSPCloud are gated by package traits (Box, PCloud), so other apps no longer download those SDKs.

Fixed

  • The merge base could be an ancestor of a better merge base, which gave false conflicts. The search is linear now, and all devices pick the same base.
  • merge() goes one head at a time, in a stable order, and keeps the heads that merged when another fails.
  • The value cache never evicted. File writes were not atomic. FileZone reported every read error as "missing".
  • Exchange.retrieve() crashed on short or long replies from a remote. send() now sends predecessors first. Multipeer dropped pushed versions that arrived out of order.
  • Snapshot restore verifies a SHA-256 from the manifest, unzips to a staging directory, and moves version files last. ZIPFoundation stops without an error at an entry it cannot read, so a damaged download used to leave a store that would not open.
  • @MergeableModel on a public struct, multiple bindings, and three Optional merge cases.
  • SQLite read errors were read as "no rows". An empty blob crashed.
  • WebDAV listings came back empty, or with empty names, from Nextcloud, ownCloud and Apache.
  • CloudKit crashed with a shared database and retried without limit. Shared databases still do not work.

Also

  • README rewritten. Every snippet was type-checked against the source.
  • First CI workflow. This PR is its first run, and the first build on Swift 6.1 (I build locally with a newer toolchain), so it may need a follow-up.
  • LICENCE.txt is now LICENSE. Package.resolved is untracked.

Tests go from 170 to 208. The CloudKit changes have no tests, because they need iCloud.

… traits

Found by a full audit (see AUDIT.md). Each fix has a test that failed first.

- Cache: regenerate() discarded the result of dropLast(), so no generation
  was ever evicted. Use removeLast().
- Optional<Mergeable>: a value inserted only by the subordinate branch was
  dropped when the ancestor was nil.
- Atomic writes for value files, version files and FileSystemExchange sends,
  so a crash or a concurrent reader cannot see a partial file.
- FileSystemExchange lists a version only when its changes file exists. This
  excludes .DS_Store and temp files orphaned by an interrupted atomic write.
- Exchange.retrieve no longer force-unwraps remote data. Missing value
  changes throw ExchangeError.missingValueChanges; entries for unrequested
  versions are ignored.
- Store.mergeHeads used try!. mergeHeads and StoreCoordinator.merge() now
  throw. SOURCE BREAKING. Samples updated.
- Package traits Box and PCloud (SE-0450). Consumers fetch the vendor SDKs
  only when they enable the trait. SOURCE BREAKING for users of LLVSBox and
  LLVSPCloud, who must now pass traits: ["Box"] or ["PCloud"].
- CLAUDE.md rewritten to match the code.
greatestCommonAncestor walked breadth-first from the second version and
returned the first common ancestor it reached. A short path (for example
through a merge) could reach an old common ancestor before a longer path
reached a more recent one. The merge was still valid, but it reported false
conflicts, and a timestamp arbiter could then discard a newer edit.

Now: collect all common ancestors, drop any that is an ancestor of another,
and choose the most recent of the rest by (timestamp, id). The choice does
not depend on argument order, so all devices pick the same base.

All three walks keep a visited set and filter the front. The original first
walk had no visited set, and Set.subtract iterates its (large) argument,
which made a 20k-version history take 19.6 s. It now takes 0.16 s.

Tests: a DAG that reproduces the wrong base, an argument-order test on a
criss-cross merge, and a timing guard on a 20k-version history.
- StoreCoordinator.merge() merges one head at a time, moves the current
  version forward after each success, and rethrows the first error after all
  heads have been tried. One head that always failed used to hide the heads
  that did merge. currentVersionUpdates now yields once per merged head.
- Store.headsToMerge(into:headSelection:) gives the heads in (timestamp, id)
  order. It was Set order, which differed per process.
- Branch metadata of the wrong type no longer traps: new
  MetadataValue.valueIfDecodable(). value() keeps its documented try!.
- FileZone.data(for:) returned nil for every read error, so an unreadable
  value looked removed. Only "no such file" now reads as nil.
- Optional<Mergeable>: both branches inserting uses salvaging(from:), as
  MergeableArbiter does for twice-inserted values. An update by the
  subordinate now beats a removal by the dominant, as it already did the
  other way around.
- Cache: each generation is its own object.
- Coordinator cache file is written atomically.
- Delete dead History.greatestCommonAncestor(ofAll:).
- Untrack Package.resolved. It is gitignored, and flips with enabled traits.
Macro:
- Generated methods take public/package from the struct. A public struct
  did not compile.
- Every binding in a declaration is merged. `var a = 0, b = 0` skipped b.

SQLite:
- forEach treated any step code other than ROW as the end of the rows, so
  BUSY or a corrupt page read as "no value". It throws unless the final
  code is DONE.
- NULL was checked on column 0 instead of the requested column, and the
  text and blob pointers were force-unwrapped. An empty blob crashed.
- 5 second busy timeout, for stores shared with app extensions.
- README: every snippet was type-checked against the source in a scratch
  package. Covers LLVSModel, package traits, all exchanges, snapshots, and
  an "Upgrading to 0.10" note. States the limits plainly: call
  reloadHistory() to see versions from other processes, SQLiteStorage is not
  thread-safe, CloudKit shared databases do not work yet.
- CHANGELOG.md for 0.10.0 (unreleased).
- .github/workflows/ci.yml: swift test, then a build with all traits, on
  macos-15 with Xcode 16.4. Not yet run on GitHub.
- LICENCE.txt renamed to LICENSE with an "MIT License" title, so GitHub and
  the Swift Package Index detect it.
- Samples: `_ = try? storeCoordinator.merge()` to silence the unused result
  warning.
- docs/ (a 2019 blog that teaches a removed Combine API) is left in place,
  because it may be served by GitHub Pages. The README no longer links to it.
…tch retry

- Exchange.send() sends versions in topological order, predecessors first.
  It was Set order, so a child could land in an earlier batch than its
  parent.
- MultipeerExchange.handlePush adds pushed versions in passes, deferring a
  version until its predecessors are present. It used to give up on the
  whole push at the first version whose predecessor had not arrived. It
  announces new versions also when a later version fails.
- CloudKitExchange.fetchCloudZoneChanges force-unwrapped the zone creation
  operation, which exists only for the private database, so a shared
  database crashed. It also reset its cached state and retried, without
  limit, on any partial failure. It now resets and retries once, and only
  when the change token really expired. No test: this needs iCloud.
  Shared databases still do not work, because the zone owner is assumed to
  be the current user.
Restore used to concatenate the chunks and unzip straight into the live
store. ZIPFoundation stops without an error at an entry it cannot read, so
a damaged download left version files in the store without their values.
History then cannot load, and Store.init fails.

- SnapshotManifest.sha256 (optional, so 0.9 manifests still decode): a
  SHA-256 of the whole archive, hashed while chunking. Restore checks size
  and hash before it unzips. Manifests without a hash are checked by size
  and by the number of version files in the archive.
- Unzip to a hidden staging directory inside the store, so the moves are
  renames on one volume. Stale staging directories are removed before a
  restore, and before a snapshot is zipped.
- Take only values/, maps/ and versions/. The archive can hold other files,
  such as the uploader's Coordinator.json.
- Decide every move first, then move values and maps, and version files
  last. A version file is what makes a version exist.
- An existing file with the same content is skipped. Any other existing
  file throws (a SQLite database cannot be merged). Restoring into a store
  directory that already had files used to fail inside the unzip.
- Write side: scan the manifest metadata before zipping, so the archive is
  a superset when the store is in use. Use the throwing FileHandle read.
…xchanging

WebDAV:
- Elements were matched only with the prefix D: (or none). A server that
  binds the DAV: namespace to another prefix gave an empty listing, with no
  error. Elements are matched on their local name now.
- The PROPFIND body asked for href as a property. Servers that report
  unknown properties (Nextcloud, ownCloud, Apache) echo an empty href in a
  404 propstat, which overwrote the real path, so every name came back
  empty. The request no longer asks for it, and the parser keeps the first
  href.
- The last path component is taken before percent-decoding, so an encoded
  slash stays part of the name.
- First tests for the parser. LLVSTests now depends on LLVSWebDAV.

Store:
- The values zone and map were lazy vars built with try!, which crashed on
  a storage error at first use, and raced when first used from two threads.
  They are made at the end of init, which throws.

StoreCoordinator:
- isExchanging is behind a Mutex. The configuration properties are
  documented as setup-only.
@drewmccormack
drewmccormack merged commit 34ff4bc into main Sep 18, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant